home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / batchut / ring14d.zip / RING.DOC < prev    next >
Text File  |  1994-03-08  |  8KB  |  205 lines
  1.  
  2.  
  3.                                   RING, v1.4
  4.                                 -------------
  5.                                 from TifaWARE
  6.  
  7.  
  8.  
  9.  
  10. What's New
  11. ----------
  12.  
  13.  
  14.      New to version 1.4 is support for DOS v4.0, v5.0, and v6.0. This
  15. required a new approach to locating the ERRORLEVEL. Adding support for
  16. other versions will be easy once the magic offsets are known.
  17.  
  18.      With version 1.3 I have substantially reorganized RING's source code,
  19. placing commonly-used procedures, equates, and macros in separate files.
  20. Sharing code in this way will make it my programming task easier. From the
  21. user's point of view, however, there should be no change in the program. 
  22.  
  23.      Version 1.2 introduces the '-e' option. If you're running DOS v3.30
  24. you can use this option to sound a bell only when the previous program had
  25. a non-zero return code; ie, exited with an error. This provides an ideal
  26. way to tell users of problems when used in a batch file.
  27.  
  28.      Many of the principal functions in RING have been completely
  29. rewritten for version 1.1. These changes will make it easier for me to
  30. revise the program. From the user's point of view, though, nothing has
  31. changed. 
  32.  
  33.  
  34.  
  35.  
  36. Introduction
  37. ------------
  38.  
  39.  
  40.      PCs have brought about great strides in productivity, but one problem
  41. has been a lack of multitasking features in MS-DOS. If you have a long job
  42. to run, you not only tie up the computer but you also must glance at the
  43. screen every once in a while to figure out if the job's finished. Either
  44. that, or you risk leaving the computer idle because you don't know how
  45. long the job will take. This is clearly inefficient. 
  46.  
  47.      RING provides a poor man's approach to multitasking. No, it doesn't
  48. let you run two programs at the same time; instead, it merely rings the
  49. console bell a few times. What's this got to do with multitasking, you
  50. ask? It's quite simple - start your job in the usual fashion, type "RING",
  51. and walk away. While your computer's doing one task, you're free to go
  52. about another task. As soon as your job has finished, the PC's console
  53. bell will sound, advising you it's ready for another job.
  54.  
  55.  
  56.  
  57.  
  58. Usage
  59. -----
  60.  
  61.  
  62.      Running this program is a breeze. Once you've placed RING.COM on your
  63. system where DOS can find it, type RING -? to display a brief help message
  64. similar to the following:
  65.  
  66.      TifaWARE RING, v1.4a, 12/28/90 - rings the console bell.
  67.      Usage: ring [-options] [count]
  68.      
  69.      Options:
  70.        -e = ring bell only if errorlevel is non-zero
  71.        -? = display this help message
  72.      
  73.      count denotes a repetition count and must be between 0 and 15.
  74.      The default value of count is 3.
  75.  
  76. [If you don't remember anything else, at least remember how to display
  77. this help message.]
  78.  
  79.      Normally, you'll invoke RING without any arguments, and the console
  80. bell will sound three times. This is probably fine in most situations. 
  81. However, RING also allows you to specify how many times the bell should
  82. ring - anything between 0 and 15 times. Thus, you could create a batch
  83. file to run a program and then ring the bell 1 time if the program was
  84. successful and 15 times otherwise. 
  85.  
  86.      With the '-e' option you can ring the console bell conditional on the
  87. previous program's return code. No matter what that program was, RING will
  88. examine its return code and sound the console bell only if it is non-zero.
  89. Further, it uses this return code as its own. Thus, the main difference
  90. between "RING -e" and the batch command "if errorlevel 1 RING" is that the
  91. first command preserves the value of ERRORLEVEL from the previous program
  92. while the second does *not*. This lets you write cleaner batch files yet
  93. still report errors. [NB: This option relies on undocumented "features" of
  94. DOS and hence may not work on all versions of DOS. Please contact me if
  95. you're not running DOS v3.30, v4.0, v5.0, or v6.0 but would still like to
  96. use this option.]
  97.  
  98.  
  99.  
  100.  
  101. If You Have Any Trouble
  102. -----------------------
  103.  
  104.  
  105.      RING will let you know of any problems that arise. Here are the
  106. messages you might see and how you should deal with them:
  107.  
  108.      ring: invalid option -- x.
  109.           - Type "RING -?" for a list of valid options.
  110.  
  111.      ring: invalid repetition count -- 100.
  112.           - The repetition count must be an unsigned integer
  113.             between 0 and 15. Note: RING reacts sensibly if 
  114.             a count of 0 is specified.
  115.  
  116.      ring: unable to locate errorlevel.
  117.           - Make sure you're using COMMAND.COM as the parent 
  118.             shell and that it's from a supported version of 
  119.             DOS.
  120.  
  121. These error messages are written to the standard error device. In this
  122. way, they won't disappear down a pipe or into a file should you redirect
  123. RING's output, although I can't imagine why you would ever do this. 
  124.  
  125.      Additionally, RING uses a return code to convey information about the
  126. success or failure of its operation. Possible return values are:
  127.  
  128.      Code      Meaning
  129.      ----      -------
  130.      0         Program completed successfully
  131.      1         Help message was displayed
  132.  
  133. if the '-e' option was *NOT* specified; otherwise, it equals whatever the
  134. previous program's return code was. You can test for these codes using the
  135. ERRORLEVEL variable in a batch file. 
  136.  
  137.  
  138.  
  139.  
  140. Requirements
  141. ------------
  142.  
  143.  
  144.      TifaWARE RING runs on machines operating under DOS v2.xx or later, and
  145. requires less than 2K of memory! [NB: To use the '-e' option, you must be
  146. operating DOS v3.30, v4.0, v5.0, or v6.0.] It uses standard DOS function
  147. calls so it should work even on machines that are not PC-compatible. 
  148.  
  149.  
  150.  
  151.  
  152. Who Owns It?
  153. ------------
  154.  
  155.  
  156.      I am releasing this program into the public domain. Since 1984 I have
  157. used public-domain software extensively, and I find it to be a terrific
  158. idea. Most programs are useful, and the source instructive. And they cost
  159. nothing! With this small contribution to the public domain I hope to pay
  160. back my gratitude to those other programmers who have made my computing so
  161. much easier.
  162.  
  163.      However, this program carries no obligation on my part to support
  164. users or provide future upgrades. I try to write clean code and believe it
  165. is "bug-free". Nevertheless, use this program ***AT YOUR OWN RISK***. Scan
  166. the source yourself, make any desired changes, and recompile the program,
  167. if possible. Make this standard practice with newly-acquired software and
  168. you'll not only protect your system from viruses but also get a better
  169. feel for exactly how programs work!
  170.  
  171.      As author of this program, I have two requests: First, please keep
  172. together the original source code, documentation, and executable if you
  173. distribute the package. This just makes it easier for others to use the
  174. software. Second, let me hear what you think of it - I'd appreciate a
  175. postcard with your comments. Enjoy!
  176.  
  177.  
  178.  
  179.  
  180. Kudos
  181. -----
  182.  
  183.  
  184.      Many thanks go to Borland for its stand-alone debugger, which greatly
  185. reduced the time spent developing this program. Thanks are also due to
  186. Josep Fortiana Gregori (D3ESJFG0@EB0UB011 on BITNET) who supplied a code
  187. fragment suggesting how to find ERRORLEVEL in RAM and to Yan Juras for
  188. pointing out where exactly to look.
  189.  
  190.  
  191.  
  192.  
  193.  
  194.                           George A. Theall
  195.  
  196.                              TifaWARE
  197.                          610 South 48th St
  198.                       Philadelphia, PA.  19143
  199.                               U.S.A.
  200.  
  201.                          george@tifaware.com
  202.                         theall@popmail.tju.edu
  203.                      theall@mcneil.sas.upenn.edu
  204.                      george.theall@satalink.com
  205.